home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 1.iso / HENSA / MISC / SHELL.ARC / Shell / h / Save102 < prev    next >
Encoding:
Text File  |  1994-11-04  |  12.3 KB  |  291 lines
  1. /*
  2.     ####             #    #     # #
  3.     #   #            #    #       #          The FreeWare C library for
  4.     #   #  ##   ###  #  # #     # ###             RISC OS machines
  5.     #   # #  # #     # #  #     # #  #   ___________________________________
  6.     #   # ####  ###  ##   #     # #  #
  7.     #   # #        # # #  #     # #  #    Please refer to the accompanying
  8.     ####   ### ####  #  # ##### # ###    documentation for conditions of use
  9.     ________________________________________________________________________
  10.  
  11.     File:    save.h
  12.     Author:  Copyright © 1994 Julian Smith and Jason Howat
  13.     Version: 1.02 (18 Jun 1994)
  14.     Purpose: Automate handling of save-as windows
  15.     Mods:    13-Jun-1994 - JPS - Added filetype handling
  16.              18-Jun-1994 - JDH - See Save.c
  17.  
  18.     04 Nov 1994 Modified to work as a Shell sublibrary - JPS.
  19.                 This is because DeskLib hasn't been released with Save 1.02 yet, but
  20.                 Shell requires Save 1.02.
  21.                 When DeskLib is released with Save version 102, Shell will use that.
  22. */
  23.  
  24. #ifndef __Shell_Save_h
  25. #define __Shell_Save_h
  26.  
  27. #ifndef __dl_event_h
  28. #include "DeskLib:Event.h"
  29. #endif
  30.  
  31.  
  32.  
  33. typedef BOOL (*Shell_Save102_filesaver)(char *f, void *ref);
  34.   /*  This type of function should save data to file given by 'f', using info
  35.    *  in 'ref'. It should return TRUE if it was successful.
  36.    *  'ref' is the (void *) originally passed to Shell_Save102_InitSaveWindowHandler
  37.    */
  38.  
  39. typedef int (*Shell_Save102_ramsaver)(
  40.   task_handle  sourcetask,                  /* our task handle */
  41.   void         *ref,
  42.   task_handle  desttask,
  43.   void         *destbuffer,
  44.   unsigned int buffersize,
  45.   int          progress       /* how many bytes have been transfered so far  */
  46.   );
  47.  
  48.   /* This type of function should Wimp_TransferBlock data. Note that you can do
  49.    * this using multiple Wimp_TransferBlock's if this is more convinient.
  50.    * Should return the total number of bytes transfered into 'destbuffer' - if
  51.    * less than buffersize, then transfer has finished. If <0, error has
  52.    * occurred.
  53.    * 'ref' is the (void *) originally passed to Save_InitSaveWindowHandler
  54.    */
  55.  
  56.  
  57.  
  58.  
  59. typedef enum
  60. {
  61.   Shell_Save102_SAVEOK    = 0,
  62.   Shell_Save102_RECEIVERFAILED,
  63.   Shell_Save102_FILESAVERFAILED,
  64.   Shell_Save102_RAMSAVERFAILED
  65. } Shell_Save102_result;
  66.  
  67.  
  68. typedef void (*Shell_Save102_resulthandler)(Shell_Save102_result result, void *ref);
  69.   /* Called after any attempt to save. */
  70.  
  71. typedef struct
  72. {
  73.   window_handle    window;        /*  Window that the save icons are in */
  74.  
  75.   union
  76.   {
  77.     unsigned int  value;
  78.     struct
  79.     {
  80.       unsigned int  is_menu         : 1;  /* Savewindow is part of menu  */
  81.       unsigned int  is_save_window  : 1;  /* Close window after save?    */
  82.       unsigned int  we_are_dragging : 1;  /* Are we dragging file icon?  */
  83.       unsigned int  quit_after_save : 1;  /* Click/drag was with Select  */
  84.       unsigned int  release_after   : 1;  /* Release all handlers when   */
  85.                                           /* the window/menu is closed?  */
  86.       unsigned int  padding         : 27;
  87.     } data;
  88.   } flags;
  89.  
  90.   icon_handle         dragsprite;
  91.   icon_handle         okbutton;
  92.   icon_handle         cancelbutton;
  93.   icon_handle         filenameicon;
  94.   Shell_Save102_filesaver      filesaver;
  95.   Shell_Save102_ramsaver       ramsaver;
  96.   Shell_Save102_resulthandler  resulthandler;
  97.   size_t              estimatedsize;
  98.   int                 filetype;
  99.   void                *ref;
  100.   int                 ram_progress;          /* Num of bytes ram-transfered. */
  101.   unsigned int        last_message_ref;      /* So we know which incoming    */
  102.                                              /* messages are replies to us   */
  103. } Shell_Save102_saveblock;
  104.  
  105.  
  106.   /*
  107.   ********************************************************************
  108.  
  109.   This struct contains all the info needed to deal with saving using
  110.   the RISC OS data transfer protocol.
  111.  
  112.   It is used internally by the Save_* functions - you shouldn't need
  113.   to use it normally. It is included here because
  114.   Save_InitSaveWindowHandler returns a pointer to it, so that you can
  115.   call Save_ReleaseSaveWindowHandler if you are using RO2 and have to
  116.   detect menu closing manually, and also you might want to change the
  117.   field 'ref' if the user presses a 'Selection' button in the save
  118.   window (you might also want to change 'filesaver' and 'ramsaver' in
  119.   this case).
  120.  
  121.   Also, you could change 'is_menu' if a menu-leaf savewindow changes
  122.   into to a free-standing savewindow (this will only work if you have
  123.   .flags.data.release_after = FALSE - the saveblock wil be free-ed and
  124.   all Event_ handlers released when the menu is closed otherwise.
  125.  
  126.   fn 'filesaver' is called when the data needs to be saved to a file.
  127.  
  128.   fn 'ramsaver' is called when the data needs to be RAM transfered.
  129.  
  130.   'ref' is passed to file/ramsaver - it should enable these functions
  131.   to save the right piece of data.
  132.  
  133.   You can change the following things after you have called
  134.   Save_InitSaveWindowHandler:
  135.  
  136.     is_menu,
  137.     is_save_window,
  138.     filesaver,
  139.     ramsaver,
  140.     resulthandler,
  141.     estimatedsize,
  142.     ref.
  143.  
  144.   Don't change any of the icon or window handles, as these will have
  145.   been used with Event_Claim, so if you change them, when Save_* calls
  146.   Event_Release, DeskLib will complain.
  147.  
  148.   Also, don't change any other fields (there is no reason to anyway)
  149.   as these are used internally and are assumed to be const.
  150.   *********************************************************************
  151.   */
  152.  
  153.  
  154.  
  155. Shell_Save102_saveblock *Shell_Save102_InitSaveWindowHandler(
  156.   window_handle      window,           /* handle of the window to deal with  */
  157.   BOOL               is_menu,          /* is this window part of a menu?     */
  158.                                        /* if TRUE Save_* will close it after */
  159.                                        /* 'Select'-saves                     */
  160.   BOOL               is_save_window,   /* is this window just a save window? */
  161.                                        /* if TRUE Save_* will close it after */
  162.                                        /* 'Select'-saves                     */
  163.   BOOL               release_after,    /* release all Save_ handlers when    */
  164.                                        /* window/menu is closed?             */
  165.   icon_handle        dragsprite,       /* handle of the dragable file-icon   */
  166.   icon_handle        okbutton,         /* handle of 'OK' or 'Save' button    */
  167.   icon_handle        cancelbutton,     /* handle of the 'Cancel' button      */
  168.   icon_handle        filenameicon,     /* handle of the writable fname icon  */
  169.   Shell_Save102_filesaver     filesaver,        /* fn which saves data to a file      */
  170.   Shell_Save102_ramsaver      ramsaver,         /* fn which does Wimp_TransferBlocks  */
  171.   Shell_Save102_resulthandler resulthandler,    /* fn to report success of save to    */
  172.   size_t             estimatedsize,    /* size of data  (estimate)           */
  173.   int                filetype,
  174.   void      *ref                       /* ref passed to all saver functions  */
  175.   );
  176.  
  177.   /*
  178.   ****************************************************************************
  179.  
  180.   To implement RISC OS saving, call this function - it does all the message
  181.   handling needed, and calls 'filesaver' or 'ramsaver' when needed, passing
  182.   'ref' to them so that they know what needs saving.
  183.  
  184.   'ismenu' should be TRUE if 'window' is part of a menu tree, and FALSE if
  185.   'window' is normal window. This is used to know when to stop handling the
  186.   save.
  187.   e.g. when menu is closed, or when save-window is closed.
  188.  
  189.  
  190.   Things you need to do:
  191.  
  192.   1  Create a conventional save-window with icons for Save, Cancel, and
  193.      dragging, and an *indirected* text icon for the filename.
  194.      (e.g. put this in a 'Templates' file).
  195.      The filename icon *must* be indirected.
  196.   2  Put a default file/leafname in to the filename icon.
  197.   3  Make the dragable icon be whatever file-icon is appropriate
  198.   4  Write a function which can save the data to a file.  *Required*
  199.   5  Write a function which can Wimp_TransferBlock the data.  *Optional*
  200.   6  Write a function to be called with result of any save  *Optional*
  201.   7  Create a reference, 'ref', to the data so that the saver functions
  202.      know what data to save.
  203.   8  Call Save_InitSaveWindowHandler
  204.      You can do this anytime - e.g. just before/after you create a menu that
  205.      includes the save window, when you open the save box in response to
  206.      (for e.g.) a F3 keypress, or when you receive a message_MENUWARNING which
  207.      heralds the opening of your save-window.
  208.  
  209.   YOU are responsible for opening the savewindow and dealing with menu
  210.   handling. All Save_* does is handle the sprite-drgging, button pressing and
  211.   data transfer protocol which originate in the save window.
  212.  
  213.   Then, when the user tries to save the data, the only thing which you get to
  214.   know about is that either your 'filesaver' or 'ramsaver' is called, with the
  215.   'ref' you originally passed to Save_InitSaveWindowHandler.
  216.   If a save is attempted, 'resulthandler' will be called, with the
  217.   success/failure of the save.
  218.  
  219.   Thats it.
  220.  
  221.   Notes:
  222.   The 'filenameicon' may be altered by Save_InitSaveWindowHandler - it
  223.   replaces the first control chr by ASCII 0, as this works with standard C
  224.   functions, and some template text icons seem to be terminated by ASCII 13.
  225.  
  226.   if you use 'release_after = FALSE', the Event_ handlers will still be in
  227.   place after the window/menu has closed. This is so you can keep a single
  228.   window for all saves, and register it with Save_ just once when your
  229.   application starts up.
  230.   If your application deals with different pieces of data, you'll have to
  231.   update the 'ref' field in the Save_saveblock returned by
  232.   Save_InitSaveWindowHandler each time the window is opened.
  233.  
  234.   Save_* registers a handler for when the save window is closed, which
  235.   Event_Release's all of the Save_* handlers for drag/click/message handling
  236.   etc. This means you can have a save window with a close icon as well
  237.   as/instead of the 'cancel' icon, and makes the whole thing a bit more robust.
  238.  
  239.   You can miss out any of the icons in the window by using a negative icon
  240.   handle. This will prevent any Event_Claim's for the icon.
  241.  
  242.   If 'ramsaver' == NULL, then 'filesaver' will always be used.
  243.   If 'resulthandler' == NULL, a default handler will be used, which will do an
  244.   'Error_Report' if a save fails.
  245.  
  246.   if 'resulthandler' != NULL, it will be called after any attempt to save the
  247.   data, with 'ref' and one of the following flags:
  248.  
  249.   save_SAVEOK = 0    receiver signals the save went OK
  250.   save_SAVERECEIVERFAILED  receiver didn't signal it has received the data
  251.   save_SAVESAVERFAILED  your 'filesaver' function signalled an error
  252.   save_SAVERAMFAILED  your 'ramsaver'  function signalled an error
  253.  
  254.   This is so that your app doesn't go away thinking data has been saved when
  255.   it hasn't. Note that your saver functions will not be aware of any problem
  256.   in the second case, where the receiver fails to load the scrap file.
  257.  
  258.   If you want to implement a 'Selection' button in the save window, you should
  259.   register a separate handler for event_CLICK on the 'Selection' button in the
  260.   save window, and when it is pressed, modify the saveblock previously
  261.   returned by Save_InitSaveWindowHandler, so that save_saveblock.ref points to
  262.   the selction data. You could also change the writable icon contents and the
  263.   'file/ramsave' functions etc etc.
  264.  
  265.   ****************************************************************************
  266.   */
  267.  
  268.  
  269.  
  270. void Shell_Save102_ReleaseSaveHandlers(Shell_Save102_saveblock *saveblock);
  271.   /* You shouldn't need this normally because menu/window closing is detected
  272.    * by SaveBoxHandler, 'cos it detects message_MENUSDELEATED and event_CLOSE.
  273.    * NB, in RO2, there is no message_MENUSDELEATED, so you will have to call
  274.    * this function when you next open a menu, or something...
  275.    *
  276.    * Also, if you want to close a free-standing (i.e. not in a menu)
  277.    * save-window when <Escape> is pressed, you will need this function.
  278.    */
  279.  
  280. void Shell_Save102_SetFiletype(Shell_Save102_saveblock *saveblock, int filetype);
  281.     /* Sets the sprite in the savewindow to be "file_..." and also alters the    */
  282.     /* saveblock so that the filetype is used whenever date is saved to the filer     */
  283.     /* or another application.                            */
  284.     /* NB this function changes the dragsprite icon is an *undirected* sprite-    */
  285.     /* -only icon. If it was previously an indirected icon, the pointer to the     */
  286.     /* indirected data is lost forever!                        */
  287.  
  288.  
  289. #endif
  290.  
  291.